


USB Driver 
Programming (2) 


writing your own device driver 


By M. Miller and C. Ehmer 


In the previous issue of Elektor Electronics, we described how device drivers 


are used. Now it’s time to modify a Cypress device driver. You only need a 


couple of programs for this, even if you have never worked with Microsoft 


Visual Studios. All of the 
necessary steps are 
described in minute detail. 


In the Windows Device Manager, you will see 
all currently connected USB devices listed 
under ‘USB Controller’. Figure 1 shows the 
entries for a USB device using the Cypress IC 
with no EEPROM and a USB data spy for Bin- 
Term. 

Writing your own complete driver ‘from 
the ground up’ is almost impossible for nor- 
mal mortals. Fortunately, Cypress provides 
the EZUSB driver not only as an installable 

version, but also in the form of source 
code. 

A device driver is divided into two parts, 
consisting of an INF file containing setup 
information and a SYS file, which is the actual 
device driver. The INF file can be edited using 
a simple text editor. A C++ compiler is 
necessary for generating the SYS file. 

If you do not already know how to pro- 
gram in C, that’s not such a big hurdle. You 
will need Microsoft Visual Studio 6 with the 
DDK (Driver Development Kit) addition for 
Windows 2000, and naturally you will also 
need the device driver source code from 
Cypress. 

Be sure to install Visual Studio and related 
packages without modifying the installation 
paths. For the device driver, you will need the 
EZ-USB Development Kit, which you have 
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Figure |. The Windows Device Manager list with a user-generated driver. 


Required items 


System requirements: 
Windows 2000 or Windows XP 
Internet access 


Programs and tools: 

MmVisual BinTerm, version 2.2.2421 or later 

Borland Delphi 6 or Microsoft Visual Basic 

Cypress Semiconductor EZ-USB Development Kit 

Microsoft Visual C++ 6 

Microsoft DDK2000 Driver Development Kit for Windows 2000 


Hardware 

A working Cypress AN2131SC IC (with EEPROM) connected to the USB, or a BinTerm 
adapter connected to the USB. The latter circuit will be described in a coming issue of 
Elektor Electronics. A BinTerm adapter connected to the USB is highly suitable for 
experimental projects, since it avoids the need to store program code in EEPROM. All 
programs are transferred to the device by BinTerm at runtime. 
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Figure 2. Circuit diagram of the EEPROM extension. 


already installed and used in Part 1 
of this series. 


Setup information 


Windows always needs an INF file 
for installing a device driver. Such a 


Table | 


[Version] 
provider=%Cypress% 
[Manufacturer ] 
sCypress%=Cypress 
[Cypress ] 


file contains the data specifying 
what should be installed, where it 
should be installed and how it 
should be installed. This file should 
be modified to meet your particular 
needs, since you don’t want the 
Cypress device driver to conflict 





with your own driver. The items to be modi- 
fied are shown in bold in Listing 1. 

Before starting to edit the INF file, save it 
with a new name, and then enter the new 
name in the [xxx.Files.Inf] section. Next, 
change the company name (‘Cypress’) to your 
own name. The descriptors that Windows 
displays in the Device Manager window are 
entered in the [Strings] section. The device 
driver that you produce should also have a 
new SYS file. Give the existing SYS file a new 
name, such as ‘MYSYS.SYS’, and correspon- 
dingly change all ‘EZUSB’ identifiers to 
‘MYSYS’. Ensure that the file name of the 
device driver does not contain any non-stan- 
dard characters or spaces — in other words, 
use only letters and numerals, with at most 
eight characters! 

The most important items are the VID and 
PID numbers. They may lie in the range of 1 
to 65534, and they are given in hexadecimal 
form. A VID number can be rented (for a fee) 
from the USB Organisation (www.usb.org) by 
anyone who wants to do so. If the VID is regi- 
stered, the product is allowed to carry a USB 
symbol and the number is guaranteed to be 
unique. However, the fee is not exactly cheap. 

The solution proposed here is to use freely 


%USB\VID_0547&PID_ 2131.DeviceDesc%=EZUSB.Dev, USB\VID_0547&PID_ 2131 


[DestinationDirs] 


EZUSB.Files.Ext = 10,System32\Drivers 


EZUSB.Files.Inf = 10,INF 
[EZUSB.Dev ] 


CopyFiles=EZUSB.Files.Ext, EZUSB.Files.iInf 


AddReg=EZUSB .AddReg 
[EZUSB.Dev.NT] 


CopyFiles=EZUSB.Files.Ext, EZUSB.Files.inf 


AddReg=EZUSB .AddReg 
[EZUSB.Dev.NT.Services ] 


Addservice = EZUSB, 0x00000002, EZUSB.AddService 


[EZUSB .AddService] 


DisplayName = %EZUSB.SvcDesc% 
ServiceBinary = %10%\System32\Drivers\ezusb.sys 


[EZUSB .AddReg ] 

HKR, ,NTMPDriver, ,ezusb.sys 
[EZUSB.Files.Ext] 
ezusb.sys 
[EZUSB.Files.Inf] 
ezusbw2k.Inf 

[Strings] 


Cypress="Cypress Semiconductor” 
USB\VID_0547&PID_2131.DeviceDesc="Cypress EZ-USB (21310/2131S/2135S) - EEPROM missing” 
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Figure 3. Testing the device driver in BinTerm. 


selected VID and PID numbers. This means 
that conflicts can arise with devices from 
other manufacturers. We suggest changing 
the VID number to ‘8B16’ and the PID number 
to ‘A001’. 


used to search for, install and load 
the device driver. 

In order to be able to use your 
VID and PID with the Cypress IC, 
you will need an EEPROM. Figure 2 
shows how an 8-KB EEPROM can be 
added to the circuit used in Part 1 of 
this article series. Program the follo- 
wing sequence of numbers into the 
EEPROM, starting at address 0: 


The VID (vendor ID), PID (product ID) and 
DID (device ID) form a set of three 16-bit data 
words that the Cypress IC reports to the ope- 
rating system. The VID and PID numbers are 


Table 2 


BOh start byte 
copy IDs 

16h, 8Bh VID = 8Bl6h 

Olh, AOh PID = A001h 

Olh, 00h DID = 0001h 


The next time the USB device is 
plugged in, the Cypress IC will 
report this new identifier to the ope- 
rating system, allowing Windows to 
install a suitable driver. 


Using C++ to modify the 


SYS device driver 

Start Visual C++ Studio, select 
‘Open Working Area’ from the ‘File’ 
menu and open the file named 


NTSTATUS DriverEntry( IN PDRIVER_OBJECT DriverObject, IN PUNICODE STRING RegistryPath) 


{ NTSTATUS ntStatus = STATUS SUCCESS; 
PDEVICE OBJECT deviceObject = NULL; 


DriverObject->MajorFunction[IRP MJ DEVICE CONTROL] = Ezusb ProcessIOCTL; 


DriverObject->DriverExtension->AddDevice = Ezusb_PnPAddDevice; 


Table 3 


NTSTATUS Ezusb CreateDeviceObject(IN PDRIVER_OBJECT DriverObject, 


IN PDEVICE OBJECT *DeviceObject, LONG Instance) 


{ NTSTATUS ntStatus; 
WCHAR deviceLinkBuffer[] = L”\\DosDevices\\Ezusb-0”; 
UNICODE STRING deviceLinkUnicodeString; 
WCHAR deviceNameBuffer[] = L”\\Device\\Ezusb-0”; 


deviceLinkBuffer[18] (USHORT) (‘0’ + Instance); 
deviceNameBuffer[14] = (USHORT) (‘0’ + Instance); 


Table 4 


NTSTATUS Ezusb ProcessIOCTL(IN PDEVICE OBJECT fdo, IN PIRP Irp) 


{ $8 8 
switch (ioControlCode) 


{ 
case IOCTL Ezusb VENDOR_REQUEST: // = $00222014 


length = Ezusb VendorRequest (fdo, (PVENDOR_REQUEST_IN) ioBuffer); 


if (length) 

{ Irp->IoStatus.Information = length; 
Irp->IoStatus.Status = STATUS SUCCESS; 

} else 

{ Irp->IoStatus.Status = STATUS SUCCESS; 

} 


break; 
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Table 5 


case IOCTL EZUSB GET DRIVER_VERSION: 
{ PEZUSB_ DRIVER_VERSION version = (PEZUSB_DRIVER_VERSION) ioBuffer; 
if (outputBufferLength >= sizeof(EZUSB_DRIVER_VERSION) ) 


{ version->MajorVersion = EZUSB MAJOR VERSION; 
version->MinorVersion = EZUSB_MINOR_VERSION; 
version->BuildVersion = EZUSB BUILD VERSION; 


Irp->IoStatus.Status = STATUS SUCCESS; 
Irp->IoStatus.Information = sizeof(EZUSB DRIVER_VERSION) ; 


else 


} 
{ Irp->IoStatus.Status = STATUS UNSUCCESSFUL; 
} 


} 


break; 


Table 6 


typedef struct _VENDOR_REQUEST_IN 


{ BYTE bRequest; 
WORD wValue; 
WORD windex; 
WORD wLength; 
BYTE direction; 
BYTE bData; 


} VENDOR_REQUEST_IN, *PVENDOR_REQUEST_IN; 


EZUSB.DSW. Next, check whether it 
is actually possible to generate the 
project. In the ‘Generate’ menu, sel- 
ect ‘Generate ezusb.sys (F'7)’. If ever- 
ything is in order, ‘0 errors, 0 war- 
nings’ will appear in the message 
window. If the installation paths 
have been changed during the 
installation, all paths in the compiler 
and linker options must be modified 
accordingly. If the code cannot 
be generated without errors or war- 
nings, the environment has not been 
configured properly. 

Under C, it is nearly impossible to 
rename an entire project, so we will 
just leave it as it is. After everything 
is finished, assign your new name 
(MYSYS.SYS) to the SYS file. 


The individual files 


The most important file is ezusb- 


Table 7 


sys.c, which contains all of the code 
for communications between the 
Windows USB device drivers and the 
application. In this article, we can 
only describe certain excerpts from 
the Cypress C source code. 

The operating system first loads 
the SYS file, and then pointers to the 
other user-written functions are 
assigned to the entry label (Driver- 
Entry), which is present in every 
device driver, to allow the operating 
system to directly execute the corre- 
sponding instructions. The operating 
system generates a new device 
using the function Ezusb_PnPAdd- 
Device, which calls Ezusb_CreateDe- 
viceObject and generates a virtual 
device name (similar to ‘COM1’ or 
‘LPT’). 

The main task is performed by 
the function Ezusb_ProcessIOCTL, 
which jumps to the Core32.dll func- 


#define Ezusb IOCTL INDEX 0x0800 
#define IOCTL_Ezusb VENDOR_REQUEST CTL _CODE(FILE DEVICE UNKNOWN, 
Ezusb IOCTL_INDEX+5, METHOD BUFFERED, FILE ANY ACCESS) 
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tion DeviceIoControl each time it is called. 

You can modify the device name according 
to your own desires, as shown in Listing 3. 
Here you should change ‘EZUSB’ to ‘MYSYS’. 
Since both of these names have the same 
length, the length declarations '18’ and ‘14’ 
need not be changed. 

As soon as this driver is loaded by the 
operating system, the user-developed pro- 
gram can use CreateFile to establish a 
connection using the name \\.\Mysys-0. In 
theory, the device driver can manage up to 
eight identical devices, which is why the 
name ends with a hyphen and a number. This 
routine is called for each DeviceIoControl 
instruction that communicates with the USB 
device (see Listing 4). A Request instruction 
for the USB device is handled using 
Ezusb_VendorRequest, but we don't want to 
discuss that in any more detail here. 

All instructions that can be executed 
using the device driver are handled in the 
Switch (ioControlCode) statement. Even ver- 
sion checking is handled using DeviceIoCon- 
trol, as can be seen in Listing 5. The major, 
minor and build numbers are located in the 
Version.h file and can be modified as you see 
fit. 

The sample Delphi program from the first 
part of the series now receives a new type 
declaration for the VENDOR_REQUEST_IN 
record. This type is defined in the file ezusb- 
sys.h from Cypress (see Listing 6). This struc- 
ture, as well as other structures for Devicelo- 
Control instructions, can be directly incorpo- 
rated into applications programmed in C, or 
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incorporated into Delphi applications in a 


derived form. 
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Links 


Cypress Semiconductor 
MmVisual BinTerm 

Keil Software 

Borland Delphi 


www.cypress.com 
www.mmvisual.de 


www.keil.com 
www.borland.com 
www.borland.com 
Microsoft www.micosoft.com 
USB- Organisation www.usb.org 
Braintechnology = www.braintechnology.de 
(source for buying Cypress ICs) 





All instructions for DeviceIoCon- 
trol are defined further on in the 
same file (see Listing 7), with the 
definitions being computed using 
the macro CTL_CODE. The best way 
to find out how the numbers are put 
together is to study the Help file. If 
you want to manually check the 
index, it’s worth knowing that the 
codes start at $00222000, with each 
subsequent code being incremented 
by $4. The code for 
IOCTL_Ezusb_VENDOR_REQUEST 
is thus $00222014. 

Now press ‘F’7’ to compile the 
source code. The result will be a file 
with the name EZUSB.SYS, which 


you should rename to MYSYS.SYS. 
Copy the modified INF file and 
EZUSB.SYS to a diskette. You have 
now produced a driver diskette for a 
Cypress IC with the VID and PID 
numbers you have defined. 

Connect the USB device having 
the corresponding VID and PID iden- 
tification to the PC. Windows will 
automatically recognise the new 
device. Use BinTerm to test the 
device driver (see Figure 3). If you 
select the ‘USB Test’ tab, you can 
enter the virtual device name and 
test communications with the 
Cypress IC. 


(020109-2) 
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